<BODY>
This package provides classes for manipulating DHCP Packets: creating, parsing and sending.
It is suitable for DHCP client, servers, relays or analysis. It currently supports only IPv4.

<p><tt>DHCPPacket</tt> is the central class allowing manipulation of DHCP packets.
A generic framework for DHCP servers is also availaible, on a development model similar to
HTTP Servlets.

<h4>Packet manipulation</h4>

Basic functions includes packet creation, modification, parsing and sending on the wire.

<p>It is centered around the 3 following classes:
	<blockquote>
	<tt><b>DHCPPacket</b></tt> packet data manipulation
	<br>
	<tt><b>DHCPConstants</b></tt> commonly used DHCP constants (better used through static imports)
		<tt>import static sf.dhcp4java.DHCPConstants.*;</tt>tt>
	<br>
	<tt><b>DHCPOption</b></tt> DHCP option manipulation, it is used internally since
		<tt>DHCPPacket</tt> provides helper functions. It is however useful if you want
		to create options lists and set them at once instead of one by one.
	</blockquote>

<p>There are two basic ways to build a new DHCPPacket object.
<p>First one is to build an object from scratch using the constructor and setters.

<pre>
DHCPPacket discover = new DHCPPacket();
discover.setOp(DHCPPacket.BOOTREQUEST);
discover.setHtype(DHCPPacket.HTYPE_ETHER);
discover.setHlen((byte) 6);
discover.setHops((byte) 0);
discover.setXid( (new Random()).nextInt() );
...
</pre>
Second is to decode a DHCP datagram received from the network.
(simple DHCP sniffer). In this case, the object is created through a singleton factory
<pre>
DatagramSocket socket = new DatagramSocket(67);
while (true) {
    DatagramPacket pac = new DatagramPacket(new byte[1500], 1500);
    socket.receive(pac);
    DHCPPacket dhcp = DHCPPacket.getPacket(pac);
    System.out.println(dhcp.toString());
}
</pre>


<H4>DHCP Servlets</h4>

This package also contains a basic framework for implementing a DHCP server.

<p>Note: this package does not contain a full blown DHCP server but only a framework
with simple examples.

<p>This framework is very close to the HTTP Servlet framework.

<h4>DHCP Servlet</h4>

The DHCPServlet is based on a request/response model.
The <tt>DHCPPacket service(DHCPPacket)</tt> is called with the incoming packet from client.
This method should return either the response DHCP packet (including address/port for sending)
or <tt>null</tt> to silently ignore the request.

<p>The <tt>service()</tt> method is systematically called, and dispatches control
to more specific methods as its default behaviour.
<blockquote><tt>doDiscover(), doRequest(), doInform(), doDecline(), doRelease()</tt></blockquote>

<p>Note: only valid DHCP datagrams are passed to servlets. Invalid packets are
discarded. However, you can override <tt>DatagramPacket serviceDatagram(DatagramPacket)</tt>
if you want a chance to treat every datagram received even malformed.

<H4>DHCP Server</h4>

The DHCP Server provided is based on a multi-thread model. The main thread listens
at the socket, then dispatches work to a pool of threads running the servlet.

<p>Configuration: the Server reads the following properties in "/DHCPd.properties"
at the root of the class path. You can however provide a properties set when
contructing the server. Default values are:
<blockquote>
<tt>serverAddress=127.0.0.1:67</tt> <i>[address:port]</i>
<br>
<tt>serverThreads=2</tt> <i>[number of concurrent threads for servlets]</i>
</blockquote>

<p>Standard way of running the Server:
<pre>
    public static void main(String[] args) {
        try {
            DHCPServer server = DHCPServer.initServer(new TrivialDHCPServlet(), null);
            new Thread(server).start();
        } catch (ServerInitException e) {
            // die gracefully
        }
    }
</pre>

</BODY>